From 6d661451965d5d0b4c8396f7d7087e9d88ebccae Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <kop@karlpinc.com>
Date: Tue, 9 May 2023 19:55:27 -0500
Subject: [PATCH] Keep sphinx venv under revision control

---
 .gitignore           |  3 +++
 Makefile             | 27 ++++++++++++++++++++++-----
 doc/requirements.txt | 24 ++++++++++++++++++++++++
 3 files changed, 49 insertions(+), 5 deletions(-)
 create mode 100644 doc/requirements.txt

diff --git a/.gitignore b/.gitignore
index 0e37677..2ceccae 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,6 @@ doc/sphinx-doc/
 
 # The python venv used by sphinx
 doc/sphinx-venv/
+
+# A generated requirements.txt file
+doc/requirements.txt.new
diff --git a/Makefile b/Makefile
index f317f5f..492999b 100644
--- a/Makefile
+++ b/Makefile
@@ -160,7 +160,8 @@ else
 HTML_IMAGE_FILES := $(SVG_FILES)
 endif
 
-CLEAN_TARGETS := $(SPHINX_PREFIX) \
+CLEAN_TARGETS := $(PREFIX)/requirements.txt.new \
+                 $(SPHINX_PREFIX) \
                  $(HTML_RST_FILES) $(LATEX_RST_FILES) \
                  $(SVG_FILES) $(PNG_FILES) \
                  $(PDF_TARGET)
@@ -193,6 +194,21 @@ mostlyclean:
 .PHONY: clean
 clean: mostlyclean destroy-sphinx-venv
 
+##
+## Update the documenation tools to newer versions with:
+##
+
+##   update-sphinx      Update sphinx venv packages to their latest versions
+.PHONY: update-sphinx
+update-sphinx: destroy-sphinx-venv install_new_sphinx
+
+##   doc/requirements.txt.new
+##                      Produce a sphinx package version requirement file
+##                      able to reproduce the existing sphinx venv
+##                      (Copy to doc/requirements.txt to make effective.)
+.PHONY: $(PREFIX)/requirements.txt.new
+$(PREFIX)/requirements.txt.new: install-sphinx
+	$(SPHINX_VENV)/bin/pip freeze > doc/requirements.txt.new
 
 ##
 ## Lesser used targets are:
@@ -216,10 +232,6 @@ install-sphinx: sphinx-venv $(SPHINX_VENV)/bin/sphinx-build
 report-old:
 	$(SPHINX_VENV)/bin/pip list -o
 
-##   update-sphinx      Update sphinx venv content to the latest versions
-.PHONY: update-sphinx
-update-sphinx: destroy-sphinx-venv install-sphinx
-
 ##   sphinx-venv        Make a virtual environment for sphinx to run from
 .PHONY: sphinx-venv
 sphinx-venv: $(SPHINX_VENV)
@@ -277,6 +289,11 @@ svg_files: $(SVG_FILES)
 
 # Ensure that sphinx is installed
 $(SPHINX_VENV)/bin/sphinx-build:
+	$(SPHINX_VENV)/bin/pip install -r $(PREFIX)/requirements.txt sphinx
+
+# Install sphinx without a requirements.txt
+.PHONY: install_new_sphinx
+install_new_sphinx: $(SPHINX_VENV)
 	$(SPHINX_VENV)/bin/pip install sphinx
 
 # Install the pdf on the website
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 0000000..3cc78df
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,24 @@
+alabaster==0.7.13
+Babel==2.12.1
+certifi==2023.5.7
+charset-normalizer==3.1.0
+docutils==0.19
+idna==3.4
+imagesize==1.4.1
+importlib-metadata==6.6.0
+Jinja2==3.1.2
+MarkupSafe==2.1.2
+packaging==23.1
+pkg_resources==0.0.0
+Pygments==2.15.1
+requests==2.30.0
+snowballstemmer==2.2.0
+Sphinx==7.0.0
+sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+urllib3==2.0.2
+zipp==3.15.0
-- 
2.34.1